bench: add experimental node:bench module - #65606

Review requested:

• @nodejs/loaders
• @nodejs/performance
• @nodejs/startup
• @nodejs/tsc

Codecov Report

❌ Patch coverage is 98.99920% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (bb5cffc) to head (69ca552).
⚠️ Report is 11 commits behind head on main.

@@            Coverage Diff             @@
##             main   #65606      +/-   ##
==========================================
+ Coverage   90.06%   90.14%   +0.08%     
==========================================
  Files         754      764      +10     
  Lines      255747   258220    +2473     
  Branches    48318    48885     +567     
==========================================
+ Hits       230327   232769    +2442     
- Misses      16550    16557       +7     
- Partials     8870     8894      +24     

@RafaelGSS probably nothing except that hopefully now it can progress. My question would be: why not vendor https://www.npmjs.com/package/bench-node?

... why not vendor ...

I initially considered vendoring one of the existing packages and opted against it in favor of a light weight, minimal, no-new-dependency approach that a more feature-rich tool like bench-node can build/iterate on. I don't consider these either/or options.

Node.js' own benchmarks demonstrate that the full set of features provided by bench-node aren't necessary for a minimal bench suite. node:bench is intended to meet the low end, minimal requirement. These don't need to compete.

We can provide stable measurement and structured result primitives without needing to ship the larger user-facing feature set and these existing tools can continue serving their current users while optionally adopting the built-in foundation. Just like node:test hasn't replaced the more sophisticated test suites like vitest.

That said, this is just a starting point. I've never been one to say "It must be done this specific way!" so all options are on the table. What I want is a built-in node --bench ... mechanism, I don't necessarily care how we get there as long as it works.

Just like node:test hasn't replaced the more sophisticated test suites like vitest.

If I can't do it with node:test I just don't worry about it.

That said, this is just a starting point. I've never been one to say "It must be done this specific way!" so all options are on the table. What I want is a built-in node --bench ... mechanism, I don't necessarily care how we get there as long as it works.

I'm with you. I just think it's easier to deliver what folks would actually want out of the module by bringing something like bench-node in. Look at the logger attempt. Instead of bringing in pino (yes, Matteo and I were/are both against that) a whole new logger was written while trying to keep the learnings from pino. That failed. But the parts undici is used for seem to be working. I think the same approach can be used.

... what folks would actually want out of the module ...

different folks "actually want" different things. You prove this point yourself with the "If I can't do it with node:test I just don't worry about it" comment. Node.js' own benchmarks don't require any of the extended features of bench-node

Node.js' own benchmarks don't require any of the extended features of bench-node

Maybe, but aren't standard library modules meant to provide utility to the community, not just the project itself?

Maybe, but aren't standard library modules meant to provide utility to the community, not just the project itself?

Why not both?

I'm intentionally designing this for both cases. Standalone utility plus primitives that can be used by tools like bench-node.

Large PR Review Guide:

Given that this is a large PR for a new subsystem... some guidance for review:

1. I would start with the bench.md and test/fixtures/bench-runner examples, and test/parallel/test-bench-* to get a sense of the overall How It Works and What It Is.
2. The design is intentionally very similar to the test runner design. Familiarity with that helps.
3. The intent here is not a full-featured bench tool like bench-node but a minimal kernel that can provide fundamental benchmark primitives suitable at the very least for our our /benchmark tooling and that full-featured bench tools can build on.
4. Once you've got an understanding of the what, look at the implementation in lib/internal
5. This PR provides the core bits, the follow-up PR here bench: additional work on node:bench #65631 includes refinements.

How does this compare to mitata?

@ronag ... I'm not familiar with mitata but I suspect the story is the same as bench-node. This is not intended to replace existing more full-featured benchmark tools, and doesn't really interfere with them in any way. Ideally this can provide useful primitives for those to build on.

CI: https://ci.nodejs.org/job/node-test-pull-request/76746/ 💚

Who's rushing to get anything merged?

Oh, sorry, misunderstand the commit-queue-rebase as intention to already move to commit-queue.

Marking the comment as resolved

I plan to merge this on 2026-09-03 if there are no issues raised by then. With green CI, two TSC approvals, and the time that's passed, it is otherwise ready to land. Note that there is a second follow-up PR here #65631 that will be marked draft until this merges.